<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
    <head>
        <title>RVM : Building the RVM</title>
	    <link rel="stylesheet" href="styles/site.css" type="text/css" />
        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">	    
    </head>

    <body>
	    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
		    <tr>
			    <td valign="top" class="pagebody">
				    <div class="pageheader">
					    <span class="pagetitle">
                            RVM : Building the RVM
                                                    </span>
				    </div>
				    <div class="pagesubheading">
					    This page last changed on Nov 12, 2008 by <font color="#0050B2">aleksey.shipilev</font>.
				    </div>

				    <p>This guide describes how to build Jikes RVM. The first section is an overview of the Jikes RVM build process and this is followed by your system requirements and a detailed description of the steps required to build Jikes RVM.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Note</b><br />
<p>Once you have things working, as described below, the <a href="Using buildit.html" title="Using buildit">buildit</a>&nbsp; script will provide a fast and easy way to build the system.&nbsp; We recommend you get things working as described below first, so you can be sure you've met the requisite dependencies etc.</p></td></tr></table></div>

<h2><a name="BuildingtheRVM-Overview"></a>Overview</h2>


<h3><a name="BuildingtheRVM-Compilingthesourcecode"></a>Compiling the source code</h3>

<p>The majority of Jikes RVM is written in Java and will be compiled into class files just as with other Java applications. There is also a small portion of Jikes RVM that is written in C that must be compiled with a C compiler such as gcc.&nbsp; Jikes RVM uses <a href="http://ant.apache.org">Ant</a> version 1.6.5 or later as the build tool that orchestrates the build process and executes the steps required in building Jikes RVM.</p>
<div class='panelMacro'><table class='noteMacro'><colgroup><col width='24'><col></colgroup><tr><td valign='top'><img src="images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"></td><td><b>Note</b><br />
<p>Jikes RVM requires a complete install of ant, including the optional tasks. These are present if you download and install ant manually. Some Linux distributions have decided to break ant into multiple packages. So if you are installing on a platform such as Debian you may need to install another package such as 'ant-optional'.</p></td></tr></table></div>

<h3><a name="BuildingtheRVM-Generatingsourcecode"></a>Generating source code</h3>

<p>The build process also generates Java and C source code based on build time constants such as the selected instruction architecture, garbage collectors and compilers. The generation of the source code occurs prior to the compilation phase.</p>

<h3><a name="BuildingtheRVM-BootstrappingtheRVM"></a>Bootstrapping the RVM</h3>

<p>Jikes RVM compiles Java class files and produces arrays of code and data. To build itself Jikes RVM will execute on an existing Java Virtual Machine and compiles a copy of it's own class files into a <b>boot image</b> for the code and data using the <b>boot image writer</b> tool. The set of files compiled is called the <a href="Primordial Class List.html" title="Primordial Class List">Primordial Class List</a>. The <b>boot image runner</b> is a small C program that loads the boot image and transfers control flow into Jikes RVM.</p>

<h3><a name="BuildingtheRVM-Classlibraries"></a>Class libraries</h3>

<p>The Java class library is the mechanism by which Java programs communicate with the outside world. Jikes RVM has configurable class library support, the most mature of which is the the <a href="http://www.gnu.org/software/classpath/">GNU Classpath</a> class library. In the release version of Jikes RVM is support for the <a href="http://harmony.apache.org/">Apache Harmony</a> class library.</p>

<p>For GNU Classpath, the developer can either specify a particular version of GNU Classpath to use. By default the build process will download and build GNU Classpath.</p>

<p>Setting the ant property <b>classlib.provider</b> to <b>Harmony</b> (<a href="#BuildingtheRVM-DefiningAntproperties">see how to define ant properties</a>) will change the build process to download and build the Apache Harmony class library.</p>

<h2><a name="BuildingtheRVM-TargetRequirements"></a>Target Requirements</h2>

<p>Jikes RVM is known to build and work on certain combinations of instruction architectures and operating systems. The following sections detail the supported architectures and operating systems.</p>

<h3><a name="BuildingtheRVM-Architectures%26nbsp%3B"></a>Architectures&nbsp;</h3>

<p>The PowerPC (or ppc) and ia32 instruction set architectures are supported by Jikes RVM.</p>

<h4><a name="BuildingtheRVM-Intel"></a>Intel</h4>

<p>Intel's Instruction Set Architectures (ISAs) get known by different names:</p>
<ul>
	<li><b>IA-32</b> is the name used to describe processors such as 386, 486 and the Pentium processors. It is popularly called <b>x86</b> or sometimes in our documentation as x86-32.</li>
	<li><b>IA-32e</b> is the name used to describe the extension of the IA-32 architecture to support 8 more registers and a 64-bit address space. It is popularly called <b>x86_64</b> or <b>AMD64</b>, as AMD chips were the first to support it. It is found in processors such AMD's Opteron and Athlon 64, as well as in Intel's own Pentium 4 processors that have <b>EM64T</b> in their name.</li>
	<li><b>IA-64</b> is the name of Intel's Itanium processor ISA.</li>
</ul>


<p>Jikes RVM currently supports the IA-32 ISA. As IA-32e is backward compatible with IA-32, Jikes RVM can be built and run upon IA-32e processors. The IA-64 architecture supports IA-32 code through a compatibility mode or through emulation and Jikes RVM should run in this configuration.</p>

<h3><a name="BuildingtheRVM-OperatingSystems"></a>Operating Systems</h3>

<p>Jikes RVM is capable of running on any operating system that is supported by the <a href="http://www.gnu.org/software/classpath/">GNU Classpath</a> library, low level library support is implemented and memory layout is defined. The low level library support includes interaction with the threading and signal libraries, memory management facilities and dynamic library loading services. The memory layout must also be known, as Jikes RVM will attempt to locate the boot image code and data at specific memory locations. These memory locations must not conflict with where the native compiler places it's code and data. Operating systems that are known to work include AIX, Linux and OSX. At one stage a port to win32 was completed but it was never integrated into the main Jikes RVM codebase.</p>

<p><b>Note:</b> Current implementation of Jikes RVM implies that system native libraries (like GTK+) have been compiled <b>with</b> frame pointers. Most of Linux distribution have frame pointers enabled in most of the packages, but some explicitly use &#45;fomit-frame-pointer thus producing the library that can't be used with JikesRVM. See <a href="http://www.nabble.com/-rvm-research---DaCapo:chart-is-broken--td20438748.html">this issue</a> for example.</p>


<h3><a name="BuildingtheRVM-SupportMatrix"></a>Support Matrix</h3>

<p>The following table details the targets that have historically been supported and the current status of the support. The target.name column is the identifier that Jikes RVM uses to identify this target.</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> target.name </th>
<th class='confluenceTh'> Operating System </th>
<th class='confluenceTh'> Instruction Architecture </th>
<th class='confluenceTh'> Address Size </th>
<th class='confluenceTh'> Status </th>
</tr>
<tr>
<td class='confluenceTd'> ia32-linux </td>
<td class='confluenceTd'> Linux <br clear="all" /> </td>
<td class='confluenceTd'> ia32 <br clear="all" /> </td>
<td class='confluenceTd'> 32 bits <br clear="all" /> </td>
<td class='confluenceTd'> OK <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> ia32-osx </td>
<td class='confluenceTd'> OSX <br clear="all" /> </td>
<td class='confluenceTd'> ia32 <br clear="all" /> </td>
<td class='confluenceTd'> 32 bits <br clear="all" /> </td>
<td class='confluenceTd'> OK <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> ia32-solaris </td>
<td class='confluenceTd'> Solaris </td>
<td class='confluenceTd'> ia32 </td>
<td class='confluenceTd'> 32 bits </td>
<td class='confluenceTd'> OK </td>
</tr>
<tr>
<td class='confluenceTd'> ia32-cygwin </td>
<td class='confluenceTd'> Windows </td>
<td class='confluenceTd'> ia32 </td>
<td class='confluenceTd'> 32 bits </td>
<td class='confluenceTd'> <a href="http://jira.codehaus.org/browse/RVM-630">WIP</a> </td>
</tr>
<tr>
<td class='confluenceTd'> ppc32-aix </td>
<td class='confluenceTd'> AIX </td>
<td class='confluenceTd'> PowerPC <br clear="all" /> </td>
<td class='confluenceTd'> 32 bits <br clear="all" /> </td>
<td class='confluenceTd'> OK <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> ppc32-linux <br clear="all" /> </td>
<td class='confluenceTd'> Linux <br clear="all" /> </td>
<td class='confluenceTd'> PowerPC <br clear="all" /> </td>
<td class='confluenceTd'> 32 bits <br clear="all" /> </td>
<td class='confluenceTd'> OK <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> ppc32-osx <br clear="all" /> </td>
<td class='confluenceTd'> OSX <br clear="all" /> </td>
<td class='confluenceTd'> PowerPC <br clear="all" /> </td>
<td class='confluenceTd'> 32 bits <br clear="all" /> </td>
<td class='confluenceTd'> OK <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> ppc64-aix <br clear="all" /> </td>
<td class='confluenceTd'> AIX <br clear="all" /> </td>
<td class='confluenceTd'> PowerPC <br clear="all" /> </td>
<td class='confluenceTd'> 64 bits <br clear="all" /> </td>
<td class='confluenceTd'> OK <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> ppc64-linux <br clear="all" /> </td>
<td class='confluenceTd'> Linux <br clear="all" /> </td>
<td class='confluenceTd'> PowerPC <br clear="all" /> </td>
<td class='confluenceTd'> 64 bits </td>
<td class='confluenceTd'> OK <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> x86_64-linux <br clear="all" /> </td>
<td class='confluenceTd'> Linux <br clear="all" /> </td>
<td class='confluenceTd'> ia32 <br clear="all" /> </td>
<td class='confluenceTd'> 32 bits&#42; <br clear="all" /> </td>
<td class='confluenceTd'> OK <br clear="all" /> </td>
</tr>
</tbody></table>
<ul>
	<li>x86_64 is currently only supported using the legacy 32bit addressing mode and instructions (<a href="http://jira.codehaus.org/browse/RVM-169">track progress on full 64bit support here</a>)</li>
</ul>


<h2><a name="BuildingtheRVM-ToolRequirements"></a>Tool Requirements</h2>


<h3><a name="BuildingtheRVM-JavaVirtualMachine"></a>Java Virtual Machine</h3>

<p>Jikes RVM requires an existing Java Virtual Machine that conforms to Java 5.0 such as <a href="http://java.sun.com">Sun JDK 1.5</a> or IBM JDK 5.0. Some Java Virtual Machines are unable to cope with compiling the Java class library so it is recomended that you install one of the above mentioned JVMs if they are not already installed on your system. The remaining build instructions assume that this Java Virtual Machine on your path. You can run "<tt>java &#45;version</tt>" to check you are using the correct JVM.</p>

<h3><a name="BuildingtheRVM-Ant"></a>Ant</h3>

<p><a href="http://ant.apache.org">Ant</a> version 1.6.5 or later is the tool required to orchestrate the build process. You can download and install the Ant tool from <a href="http://ant.apache.org/">http://ant.apache.org/</a> if it is not already installed on your system. The remaining build instructions assume that $ANT_HOME/bin is on your path. You can run "<tt>ant &#45;version</tt>" to check you are running the correct version of ant.</p>

<h3><a name="BuildingtheRVM-CToolChain"></a>C Tool Chain</h3>

<p>Jikes RVM assumes that the GNU C Tool Chain is present on the system or a tool chain that is reasonably compatible. Most modern &#42;nix environments satisfy this requirement.</p>

<h3><a name="BuildingtheRVM-Bison"></a>Bison</h3>

<p>As part of the build process, Jikes RVM uses the bison tool which should be present on most modern &#42;nix environments.</p>

<h3><a name="BuildingtheRVM-Perl"></a>Perl</h3>

<p>Perl is trivially used as part of the build process but this requirement may be removed in future releases of Jikes RVM. Perl is also used as part of the regression and performance testing framework.</p>

<h3><a name="BuildingtheRVM-Awk"></a>Awk</h3>

<p>GNU Awk is required as part of the regression and performance testing framework but is not required when building Jikes RVM.</p>

<h3><a name="BuildingtheRVM-ExtratoolsrecommendedforSolaris"></a>Extra tools recommended for Solaris</h3>

<p>pkg-get will greatly simplify installing GNU packages on Solaris. Our patches require that GNU patch is picked up in preference to Sun's, to achieve this, for example, you can create a symbolic link to /usr/bin/gpatch from /opt/csw/bin/patch and make sure /opt/csw/bin is in your path before /usr/bin.</p>

<h2><a name="BuildingtheRVM-Instructions"></a>Instructions</h2>


<h3><a name="BuildingtheRVM-DefiningAntproperties"></a>Defining Ant properties</h3>

<p>There are a number of ant properties that are used to control the build process of Jikes RVM. These properties may either be specified on the command line by "<tt>&#45;Dproperty=variable</tt>" or they may be specified in a file named "<tt>.ant.properties</tt>" in the base directory of the jikesrvm source tree. The "<tt>.ant.properties</tt>" file is a standard Java proeprty file with each line containing a "<tt>property=variable</tt>" and comments starting with a <em>&#35;</em> and finishing at the end of the line. The following table describes some properties that are commonly specified.</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Property </th>
<th class='confluenceTh'> Description </th>
<th class='confluenceTh'> Default </th>
</tr>
<tr>
<td class='confluenceTd'> host.name </td>
<td class='confluenceTd'> The name of the host environment used for building Jikes RVM. The name should match one of the files located in the <a href="http://svn.sourceforge.net/viewvc/jikesrvm/rvmroot/trunk/build/hosts/"><tt>build/hosts/</tt></a> directory minus the '<tt>.properties</tt>' extension. <br clear="all" /> </td>
<td class='confluenceTd'> None </td>
</tr>
<tr>
<td class='confluenceTd'> target.name </td>
<td class='confluenceTd'> The name of the target environment for Jikes RVM. The name should match one of the files located in the <a href="http://svn.sourceforge.net/viewvc/jikesrvm/rvmroot/trunk/build/targets/"><tt>build/targets/</tt></a> directory minus the '<tt>.properties</tt>' extension. This should only be specified when cross compiling the Jikes RVM. See <a href="Cross-Platform Building.html" title="Cross-Platform Building">Cross&#45;Platform Building</a> for a detailed description of cross compilation. <br clear="all" /> </td>
<td class='confluenceTd'> <tt>${host.name</tt>} <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> config.name </td>
<td class='confluenceTd'> The name of the configuration used when building Jikes RVM. The name should match one of the files located in the <a href="http://svn.sourceforge.net/viewvc/jikesrvm/rvmroot/trunk/build/configs/"><tt>build/configs/</tt></a> directory minus the '<tt>.properties</tt>' extension. This setting is further described in the section <a href="Configuring the RVM.html" title="Configuring the RVM">Configuring the RVM</a>. </td>
<td class='confluenceTd'> None </td>
</tr>
<tr>
<td class='confluenceTd'> patch.name <br clear="all" /> </td>
<td class='confluenceTd'> An identifier for the current patch applied to the source tree. See <a href="Building Patched Versions.html" title="Building Patched Versions">Building Patched Versions</a> for a description of how this fits into the standard usage patterns of Jikes RVM. </td>
<td class='confluenceTd'> "" </td>
</tr>
<tr>
<td class='confluenceTd'> components.dir <br clear="all" /> </td>
<td class='confluenceTd'> The directory where Ant looks for external components when building the RVM. <br clear="all" /> </td>
<td class='confluenceTd'> <tt>${jikesrvm.dir}/components</tt> <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> dist.dir <br clear="all" /> </td>
<td class='confluenceTd'> The directory where Ant stores the final Jikes RVM runtime. <br clear="all" /> </td>
<td class='confluenceTd'> <tt>${jikesrvm.dir}/dist</tt> <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> build.dir <br clear="all" /> </td>
<td class='confluenceTd'> The directory where Ant stores the intermediate artifacts generated when building the Jikes RVM. </td>
<td class='confluenceTd'> <tt>${jikesrvm.dir}/target</tt> <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> protect.config-files </td>
<td class='confluenceTd'> Define this property if you do not want the build process to update configuration files when auto downloading components. </td>
<td class='confluenceTd'> (Undefined) </td>
</tr>
<tr>
<td class='confluenceTd'> components.cache.dir </td>
<td class='confluenceTd'> The directory where Ant caches downloaded components.&nbsp; If you explicitly download a component, place it in this directory. <br clear="all" /> </td>
<td class='confluenceTd'> (Undefined, forcing download) </td>
</tr>
</tbody></table>
<p>At a minimum it is recommended that the user specify the <tt>host.name</tt> property in the "<tt>.ant.properties</tt>" file.</p>

<p>The configuration files in "<a href="http://svn.sourceforge.net/viewvc/jikesrvm/rvmroot/trunk/build/targets/"><tt>build/targets/</tt></a>" and "<a href="http://svn.sourceforge.net/viewvc/jikesrvm/rvmroot/trunk/build/hosts/"><tt>build/hosts/</tt></a>" are designed to work with a typical install but it may be necessary to overide specific properties. The easiest way to achieve this is to specify the properties to override in the "<em>.ant.properties</em>" file.</p>

<h3><a name="BuildingtheRVM-SelectingaConfiguration"></a>Selecting a Configuration</h3>

<p>A "configuration" in terms of Jikes RVM is the combination of build time parameters and component selection used for a particular Jikes RVM image.  The <a href="Configuring the RVM.html" title="Configuring the RVM">Configuring the RVM</a> section describes the details of how to define a configuration. Typical configuration names include;</p>
<ul>
	<li><b>production</b>: This configuration defines a fully optimized version of the Jikes RVM.</li>
	<li><b>development</b>: This configuration is the same as production but with debug options enabled. The debug options perform internal verification of Jikes RVM which means that it builds and executes more slowly.</li>
	<li><b>prototype</b>: This configuration is compiled using an unoptimized compiler and includes minimal components which means it has the fastest build time.</li>
	<li><b>prototype-opt</b>: This configuration is compiled using an unoptimized compiler but it includes the adaptive system and optimizing compiler. This configuration has a reasonably fast build time.</li>
</ul>


<p>If a user is working on a particular configuration most of the time they may specify the config.name ant property in "<tt>.ant.properties</tt>" otherwise it should be passed in on the command line "<tt>&#45;Dconfig.name=...</tt>".</p>

<h3><a name="BuildingtheRVM-FetchingDependencies"></a>Fetching Dependencies</h3>

<p>The Jikes RVM has a build time dependency on the <a href="http://www.gnu.org/software/classpath/">GNU Classpath</a> class library and depending on the configuration may have a dependency on <a href="http://www.cs.kent.ac.uk/projects/gc/gcspy/">GCSpy</a>. The build system will attempt to download and build these dependencies if they are not present or are the wrong version.</p>

<p>To just download and install the <a href="http://www.gnu.org/software/classpath/">GNU Classpath</a> class library you can run the command "<tt>ant &#45;f build/components/classpath.xml</tt>". After this command has completed running it should have downloaded and built the <a href="http://www.gnu.org/software/classpath/">GNU Classpath</a> class library for the current host. See the <a href="Using GCSpy.html" title="Using GCSpy">Using GCSpy</a> page for directions on building configurations with GCSpy support.</p>

<p>If you wish to manually download components (for example you need to define a proxy, so ant is not correctly downloading), you can do so and identify the directory containing the downloads using "<tt>&#45;Dcomponents.cache.dir=&lt;download directory&gt;</tt>" when you build with ant.</p>

<h3><a name="BuildingtheRVM-BuildingtheRVM"></a>Building the RVM</h3>

<p>The next step in building Jikes RVM is to run the ant command "<tt>ant</tt>" or "<tt>ant &#45;Dconfig.name=...</tt>". This should build a complete RVM runtime in the directory "${dist.dir}/${config.name}_${target.name}". The following table describes some of the ant targets that can be executed. A complete list of documented targets can be listed by executing the command "<tt>ant &#45;projecthelp</tt>"</p>
<table class='confluenceTable'><tbody>
<tr>
<th class='confluenceTh'> Target </th>
<th class='confluenceTh'> Description </th>
</tr>
<tr>
<td class='confluenceTd'> check-properties </td>
<td class='confluenceTd'> Check that all the required properties are defined. </td>
</tr>
<tr>
<td class='confluenceTd'> compile-mmtk </td>
<td class='confluenceTd'> Compile MMTk toolkit. <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> prepare-source </td>
<td class='confluenceTd'> Generate configuration independent source code if required or force.generation property is set. </td>
</tr>
<tr>
<td class='confluenceTd'> prepare-config-source </td>
<td class='confluenceTd'> Generate source code for the current configuration if required or force.generation property is set. <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> main or runtime <br clear="all" /> </td>
<td class='confluenceTd'> Build a runtime image. </td>
</tr>
<tr>
<td class='confluenceTd'> clean </td>
<td class='confluenceTd'> Remove the build and image directory for the current configuration. <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> very-clean </td>
<td class='confluenceTd'> As with clean but also remove Java files generated by scripts. <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> real-clean </td>
<td class='confluenceTd'> As with very-clean but remove all compiled images. <br clear="all" /> </td>
</tr>
<tr>
<td class='confluenceTd'> profiled-image </td>
<td class='confluenceTd'> Compile a baseline version of the RVM for profiling then use the profile information to recompile the given <tt>config.name</tt> image. <br clear="all" /> </td>
</tr>
</tbody></table>

<h3><a name="BuildingtheRVM-RunningtheRVM"></a>Running the RVM</h3>

<p>Jikes RVM can be executed in a similar way to most Java Virtual Machines. The difference is that the command is "<tt>rvm</tt>" and resides in the runtime directory (i.e. "${dist.dir}/${config.name}_${target.name}"). See <a href="Running the RVM.html" title="Running the RVM">Running the RVM</a> for a complete list of command line options.</p>

				    
                    			    </td>
		    </tr>
	    </table>
	    <table border="0" cellpadding="0" cellspacing="0" width="100%">
			<tr>
				<td height="12" background="http://docs.codehaus.org/images/border/border_bottom.gif"><img src="images/border/spacer.gif" width="1" height="1" border="0"/></td>
			</tr>
		    <tr>
			    <td align="center"><font color="grey">Document generated by Confluence on Jun 10, 2009 09:12</font></td>
		    </tr>
	    </table>
    </body>
</html>